home
download
documentation
mailing lists
wiki
IRC
forums
daily builds
feature requests
bug reports
patches

The Simplified Guide To Compiling The Rockbox Source Code

• Introduction
• What You Will Need
• Installation
• Getting The Source Code
  • From CVS
  • From Daily Build page
• Compiling The Source Code
  • Creating The Tools
  • Adding Patches
  • Configuring Build
  • Finally Compiling
• Adding Patches
  • Preparation
  • Patching
• Keeping source upto date with CVS
• Producing a diff of your changes with CVS
• Feedback & Thanks

Introduction

This page aims to provide a simple step by step guide on how to apply patches to Rockbox and then compile the source code to give the final product.

Instructions for doing are available in many forms throughout this website, but the majority of them have been written for those who know the basics of programming. To aid those who are attempting this for the first time and desperately want to customise their Rockbox software, I have decided to create this page. I hope it helps :-)

NOTE: This guide is for Windows users only!

What You Will Need

Rockbox Development Kit - http://homepage.ntlworld.com/cyborgsystems/CS_Main/RockBox/Win32_DevKit/RockBox-DevKit_v313.exe (approx. 9.51 Mb)

Patch - http://www.base15.com/patch-2.5.9-3-bin.zip (approx. 138 Kb)

Installation

Rockbox Development Kit -

• double click on RockBox-DevKit_v313.exe and extract all the files to a folder of your choice
• go to your C Drive and create a folder called Rockbox so that the path is to that folder is C:\Rockbox\
• Note - I am using a folder called Rockbox in my C Drive because I find it easier that way, but you can call the folder anything you like and create it where ever you want
• once the extraction is complete, open Rockbox-DevKit_v313 (within the extracted folder) and move its contents to C:\Rockbox
• there is a folder called setup, and within that folder there is a file called SETUP.bat - run this file

Patch -

• extract patch-2.5.9-3-bin.zip to a location of your choice
• move the contents of the extracted folder to C:\Rockbox

Getting The Source Code

There are two ways to get the source. From CVS and manually downloading from the Daily Build page.

From CVS

Check out source.
cvs -d:pserver:anonymous@rockbox.haxx.se:/cvsroot/rockbox login
cvs -z3 -d:pserver:anonymous@rockbox.haxx.se:/cvsroot/rockbox co rockbox
When prompted for a password just press enter.
A "rockbox" directory will be created in your current directory and all the source files will be placed there.

For more infomation see the "Accessing source code via CVS" page http://www.rockbox.org/cvs.html.

From Daily Build page

Usually there is two different versions of the source code available... the Daily Build and the Bleeding Edge Build. Both of these builds are available at http://www.rockbox.org/daily.shtml The Bleeding Edge build contains the latest changes made by the Developers whereas the Daily Build is produced automatically at the same time every day. If you are new to Rockbox I would recommend downloading the Daily Build, because the Bleeding Edge build could contain bugs that the Developers are not aware of yet. In addition to this, older builds can also be downloaded, so all in all, its pretty much up to you what you decide to download.

• Once the source code file has been downloaded, you should have a file called rockbox-daily-XXXXXXXX.tar.gz (where XXXXXXXX is the date) or rockbox-bleeding.tar.gz
• Make your way back to C:\Rockbox\, open the folder called Home and the folder called guest within that. Move your newly downloaded file into this folder (C:\Rockbox\home\guest)
• Go back to C:\Rockbox\ and double click on _RockBox.bat
• Once that is open, type dir and it should show the name of the file you have just copied into the folder (if this doesn't work, don't worry too much... you can just copy the filename from elsewhere)
• It may be easier to rename the .tar.gz file to something easier, such as 1.tar.gz or when typing in the filename, just start of with the first few letters and then press the Tab key, which will autocomplete the name
• Now, type daily filename.tar.gz, where filename is the name of the file... obviously
• You should notice the command working away, before it comes back to the prompt
• Some people have had some problems with the dir and daily commands, so if that is the case, you can manually extract the file by using WinRAR *If you go back into the folder where you placed the file in the first place, you should see a new folder containing all the extracted files

Compiling The Source Code

Creating The Tools

• Now back in the cmd window (the one with the black background and white/grey/green writing) type cd foldername, where foldername is the name of the folder where the extracted files went to, and then press Enter
• Pressing the Enter button on the keyboard executes any command
• Typing the command dir shows the contents of the current folder
• Typing the command cd followed by the name of a folder, it enters that folder
• Typing the command cd.. goes back out of the folder
• So you want to make your way to the tools folder, so type cd tools
• In this folder, type make

Adding Patches

• Please refer to the Adding Patches section lower down the page

Configuring Build

• Now that the tools required to compile the source code have been created, it is time to compile the code
• Move back out of the tools folder by typing cd..
• Create a new folder for the compiling by typing mkdir folder, where folder is the name of the folder (I tend to call it build)
• Enter that folder by typing cd folder, where folder is the name you chose for the folder
• In that folder type rbconf which will bring up a list of all possible devices
• Select your device by typing in the corresponding number
• Next you will be given the option of the build type... just type N for Normal Build
• Then select the desired language from the list... eg. for English type 6
• Once that is completed, you should see the text Created Makefile

Finally Compiling

• Now type make
• Sit back and watch the files being compiled... this process should not take more than 5 minutes (may take a little more if you have a slow computer)
• Once it has compiled, type make zip
• This will create a file called rockbox.zip within the folder you made (in my case build)
• This zip file will be identical to the already compiled Rockbox software for the date of your source code, which you could have downloaded from this website

Well Done! If you have reached this far then you have successfully compiled your own source code. There is obviously no point in doing this if you are not going to modify the code in any way, so the next part looks at how to encorporate patches into the source code.

Adding Patches

Patches are modifications which have not yet been included in the daily builds by the Developers. The patches are not made by the Developers so there is a chance that they could contain bugs, but it is unlike that they could actually harm your player. These patches can be downloaded from http://www.rockbox.org/patches.shtml. These patches easily allow you to edit certain source code files, but if these files have been updated by the Developers, and the patch has not been modified for the new files, it is unlikely that it will work. Depending on what files a patch modifies, you may only be able to apply 1 patch, because if the first patch modifies a file, the contents of the file would then change and the second patch would have difficulty in updating it. However, if the patch you want to apply, is only going to patch a file that you have never patched before, then it should still work.

Preparation

• Download the patch file afer following the links on http://www.rockbox.org/patches.shtml... the file should either end in .diff or .patch
• This file can be opened by Wordpad - double click on the file and select Wordpad as the program
• You can see what files this patch is going to edit... for example:

Index: apps/status.c
===================================================================
RCS file: /cvsroot/rockbox/apps/status.c,v
retrieving revision 1.72
diff -u -r1.72 status.c
--- apps/status.c   6 Jul 2005 22:57:54 -0000   1.72
+++ apps/status.c   1 Aug 2005 15:34:12 -0000
@@ -82,6 +82,13 @@
     status_draw(false);
 }
 +enum playmode status_get_ffmode(void)

• The above code is part of a patch file... you can see that this part of the code is going to modify the file status.c in the apps folder
• A patch or diff file can contain many sections of code like this and modify many files in one go
• Move the .diff or .patch file to the source folder (eg C:\Rockbox\home\guest\rockbox-daily-XXXXXXXX\)

Patching

• Back in the DevKit window, go to the directory containing the patch (use the commands mentioned earlier on in this guide)
• Type the command patch -p0 < patchfilename --binary where patchfilename is the name of the patch file you downloaded (eg jpeg.diff)
• The Patch program should then patch the file... if this fails then try patch -p1 < patchfilename --binary instead (increase the number each time, up to a maximum of 5)
• After you have finished patching the files, simply continue with Configuring Build instructions above
• Sometimes (if the patch file isn't correctly generated) having the patch file in the root of the source files does not work, so move the patch file to the location of the files to be patched and run continue the steps below from there. In addition to this, some patches may required patching files in different locations... so repeat the process at all the different locations, until all the files have been patched (Note: first try all the patching attempts below before resorting to this)
• If this fails too, then it is most likely because the patch was not designed for that particular version of the file you are patching, if this is the case then you will usually see messages telling you that a HUNK has failed eg. HUNK #2 failed at line 345 or something similar. Unless you like programming there isn't much you can do about this.
• If you wish to remove a patch then you just need to add a -R switch eg. patch -p0 -R < patchfilename --binary. As you can see this is identical to the command used for applying the patch but with a -R before the <.

Keeping source upto date with CVS

If you downloaded the source using CVS you can use CVS to keep your source tree upto date. First cd into the "rockbox" directory where the source was downloaded.
cd rockbox
Now update
cvs update -dP
If you have modified any source files cvs will try to merge any changes so you don't need to apply patches again after updating.

Producing a diff of your changes with CVS

For more information on using CVS see Bluechip and Linus's irc chat:
http://homepage.ntlworld.com/cyborgsystems/CS_Main/RockBox/Win32_DevKit/HowTo_CVS.html

and the "Accessing source code via CVS" page http://www.rockbox.org/cvs.html.

Feedback & Thanks

If you have any comments or ideas on how to improve this guide, please feel free to email me at rockbox [at] hirenshah [dot] co [dot] uk

Thanks also goes to the following people for helping me correct the mistakes and improve this page (I apologise if I missed your name out): LinusN, rasher, ENWOD, ally, Mikerman and Mmmm

{ Edit | View raw | Attach | Ref-By | Printable | Diffs | r1.86 | > | r1.85 | > | r1.84 | More }

Revision r1.86 - 01 Sep 2005 - 10:41 GMT - MartinScarratt Parents: TWikiUsers > HirenShah	Copyright © 1999-2005 by the contributing authors.